home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / TGCBOR20.ARJ / TUTOR.COM / TWQUICK.TXT < prev   
Text File  |  1991-08-27  |  13KB  |  445 lines
  1. TEGL WINDOWS
  2.  
  3. The high-level windows in the TEGL WINDOWS TOOLKIT provide a consistent
  4. graphical interface for your application. Many routines are provided
  5. that are associated with a window or are window relative. A number of
  6. devices are provided that would require a fair bit of coding using the
  7. lower levels of the toolkit.
  8.  
  9.        * Header
  10.        * Local menus
  11.        * Minimize & Maximise buttons
  12.        * Resizers
  13.        * Sliders
  14.        * Dialog management
  15.        * World Coordinates
  16.  
  17. A drawback to the high-level windows is the necessity of coding a
  18. redraw event for windows that are resizeable.
  19.  
  20. Here is a simple window:
  21.  
  22. BEGINFILE> twwin1.c
  23.   /* -- twwin1.c */
  24.  
  25. #include "teglsys.h"
  26.  
  27. winframeptr  wf;
  28.  
  29.  
  30. void main(void)
  31. {
  32.   tweasystart();
  33.  
  34.   twinit(&wf,100,50,300,150);
  35.   twsetheader(wf,"A Simple Window");
  36.   twdrawwindowframe(wf);
  37.  
  38.   teglsupervisor();
  39. }
  40.  
  41.  
  42.  
  43. ENDFILE>
  44.  
  45. When you compile and run this program you'll get a window with a header
  46. and resize areas.
  47.  
  48. Lets examine what each step in this programs does.
  49.  
  50. The first call to tweasystart does the graphics system and window
  51. manager initialization including autodetection of the graphics
  52. hardware and clearing the screen. Additionally it places an exit
  53. button in the lower right corner of the screen so you can always exit
  54. your program.
  55.  
  56. twinit creates a window frame (the first parameter wf is a
  57. winframeptr) memory block, the numbers indicate the screen area
  58. that the window should occupy (x1, y1, x2, y2). twinit must always
  59. be called before an other routines that have a winframeptr as their
  60. first argument.
  61.  
  62. twsetheader says this window will have a header displayed (default
  63. is no header) and what is displayed in it.
  64.  
  65. twdrawwindowframe actually draws the window on the screen. This is
  66. always called after all the conditions for a window have been set.
  67.  
  68. teglsupervisor is the event-supervisor. It will poll for events
  69. (key-presses and mouse clicks) and call up the appropriate event-handler
  70. as required.
  71.  
  72. The high-level windows have a number of pre-defined event-handlers
  73. that are automatically installed. There is the resizing events which
  74. look after the borders of the window so that a mouse click can stretch
  75. or shrink the window. Also there is the minimize and maximize buttons.
  76. The minimize button will shrink a window to an icon while the maximize
  77. button expands it to fill the entire screen.
  78.  
  79. CONTROL FUNCTIONS
  80.  
  81. winframeptr findwinframe(imagestkptr frame);frame : ImageStkPtr);
  82.  
  83. This function is used to locate a winframeptr that is associated with
  84. a frame (imagestkptr). It is called on entry to an event-handler to
  85. determine what window invoked it.
  86.  
  87. void twselect(winframeptr wf);
  88.  
  89. This function will select the window. This should be called on entry
  90. to any event-handler that uses a window, it does internal checks and
  91. sets the viewport to the working area.
  92.  
  93. GLOBAL WINDOW SETUP
  94.  
  95. twsetglobalbuttonsize(char width, char height);
  96.  
  97. Set the size of the buttons on the window. Generally if the defaults
  98. are not satisfactory then this can be changed but should be done at
  99. start up before any windows are drawn. This affects all windows.
  100.  
  101. twsetglobalslidersize(char updown, char leftright);
  102.  
  103. Sets the size of the slider thumb (the button that slides). This only
  104. affects on dimension of the slider thumbs, the other is set to conform
  105. to the button sizes.
  106.  
  107. twsetglobresizearea(char width, char height);
  108.  
  109. Sets the size of the resize corner areas of the window border.
  110. Width is the x distance (in pixels) and Height is the y distance.
  111. The thickness of the border is used to complete the resize areas, this
  112. defaults to 4 pixels and can be changed on individual windows.
  113.  
  114. twsetheaderfont(fontptr font);
  115.  
  116. Sets the font that all subsequent windows will use for headers and
  117. menus.
  118.  
  119. This example sets these global items to illustrate how the window
  120. style is affected. The best use of these items is to control the
  121. window look on different video displays and would best be set at
  122. the start of a program and left alone during the run.
  123.  
  124. BEGINFILE> twwin2.c
  125.   /* -- twwin2.c */
  126.  
  127. #include "teglsys.h"
  128.  
  129. winframeptr  wf;
  130.  
  131.  
  132.  
  133.  
  134. void main(void)
  135. {
  136.   tweasystart();
  137.  
  138.   twsetglobalbuttonsize(24,12);
  139.   twsetglobalslidersize(36,8);
  140.   twsetglobalresizearea(50,20);
  141.   twsetheaderfont(&f8x12bol);
  142.   twinit(&wf,100,50,300,170);
  143.     twsetheader(wf,"Common Window characteristics");
  144.     twsetwindowstyle(wf,stdbox);
  145.     twsetupdownslider(wf,TRUE);
  146.     twsetleftrightslider(wf,TRUE);
  147.   twdrawwindowframe(wf);
  148.  
  149.   teglsupervisor();
  150. }
  151.  
  152.  
  153.  
  154. ENDFILE>
  155.  
  156. WINDOW FEATURES
  157.  
  158. The following functions set features on a window that affect only that
  159. window. Note that each one requires a winframeptr at the first
  160. argument.
  161.  
  162. twsetbordercolor(winframeptr wf, char color);
  163.  
  164. Sets the color of the window border. The border is the one pixel outline.
  165.  
  166. twsetcloseevent(winframeptr wf, callproc closeevent);
  167.  
  168. Sets the event to call when a window is disposed of. The closeevent does
  169. not have to be set (a default one is in place).
  170.  
  171. twsetdisplayfont(winframeptr, fontptr font);
  172.  
  173. Sets the font to use with the window. This affects the header and menus.
  174.  
  175. twsetmaximize(winframeptr wf, unsigned char tf);
  176.  
  177. Sets whether a window is minimize/maximizeable. If TRUE then the
  178. window will have the minimize/maximize buttons. Only has an effect on
  179. windows with a header.
  180.  
  181. twsetredraw(winframeptr wf, callproc redraw);
  182.  
  183. Sets the redrawing function for a window. The redrawing function is
  184. an event-handler. This function is called after the kernel draws the
  185. window (border, buttons, menu etc.) when first created and any time the
  186. window must be redraw, like after it has been re-sized.
  187.  
  188. twsetheader(winframeptr wf, char *s);
  189.  
  190. Sets the window header to s. Window header must be set to enable the
  191. minimize/maximize buttons.
  192.  
  193. twsetthickness(winframeptr wf, char thickness);
  194.  
  195. Sets the thickness of the window border. Thickness cannot be less than
  196. one. The thickness affects the size of the resize areas (if resizing is
  197. enabled for the window).
  198.  
  199. twsetwinframecolor(winframeptr wf, char color1, char color2);
  200.  
  201. Sets the colors to use on the upper left and lower right of the window.
  202.  
  203. twsetwindowstyle(winframeptr wf, framedrawfunc style);
  204.  
  205. Sets the drawing function to draw the border of the window frame.
  206. Currently there are two drawing functions, stdbox and bevbox.
  207.  
  208. ------------------------------------------------------------------
  209.  
  210. This example uses many of window features, you don't need to set them
  211. all, the defaults are usually fine, but by changing them around you
  212. can see the effects.
  213.  
  214. BEGINFILE> twwin3.c
  215.   /* -- twwin3.c */
  216.  
  217. #include "teglsys.h"
  218.  
  219. winframeptr  wf;
  220.  
  221.  
  222.  
  223.   /* -- RedrawIt is a standard event-handler. It is called after  */
  224.   /* -- the window standard items have been drawn.  */
  225.  
  226.  
  227. unsigned redrawit(imagestkptr  ifs, msclickptr   ms)
  228.   { winframeptr  wf;
  229.  
  230.     wf = findwinframe(ifs);
  231.     twputpict(wf,1,1,imageSYSTEM,BLACK);
  232.     return 0;
  233.   }
  234.  
  235.   /* -- this is the close event for the window.  */
  236.  
  237.  
  238. unsigned closeit(imagestkptr  ifs, msclickptr   ms)
  239.   { winframeptr  wf;
  240.       int      i;
  241.       int      color;
  242.  
  243.     wf = findwinframe(ifs);
  244.     prepareforupdate(ifs);
  245.       /* -- prove that we are going through here  */
  246.     color = 0;
  247.     for (i = 0; i <= 100; i++)
  248.       {
  249.     twsetfillcolor(wf,color);
  250.     twclear(wf);
  251.     color++;
  252.     if (color > 15) color = 0;
  253.       }
  254.     commitupdate();
  255.       /* -- then call close to actually dispose of the window  */
  256.     twclose(wf);
  257.     return 0;
  258.   }
  259.  
  260.  
  261.  
  262. void main(void)
  263. {
  264.   tweasystart();
  265.  
  266.   twinit(&wf,100,50,300,170);
  267.     twsetheader(wf,"Window characteristics");
  268.     twsetthickness(wf,6);
  269.     twsetfillcolor(wf,GREEN);
  270.     twsetbordercolor(wf,BLACK);
  271.     twsetwinframecolors(wf,CYAN,MAGENTA);
  272.     twsetmaximize(wf,FALSE);   /* -- no minimize/maximize */
  273.     twsetwindowstyle(wf,bevbox);
  274.     twsetredraw(wf,redrawit);
  275.     twsetcloseevent(wf,closeit);
  276.   twdrawwindowframe(wf);
  277.  
  278.   teglsupervisor();
  279. }
  280.  
  281.  
  282.  
  283. ENDFILE>
  284.  
  285. WINDOW FUNCTIONS
  286.  
  287. twclear(winframeptr wf);
  288.  
  289. Clears the window to the color set by twsetfillcolor.
  290.  
  291. twscrolldown(winframeptr wf, int num);
  292. twscrollup(winframetpr wf, int num);
  293.  
  294. These functions will scroll the working area of the window up or down
  295. by Num pixels. The area cleared is filled using the current fillcolor
  296. set by twsetfillcolor.
  297.  
  298. Sliders -
  299.  
  300. twsetupdownslider(winframeptr wf, unsigned char active);
  301. twsetleftrightslider(winframeptr wf, unsigned char active);
  302.  
  303. These enable (or disable) the sliders from being attacted to a
  304. window. TRUE turns sliders on, FALSE turns them off. If the slider
  305. is changed after the window is displayed then it must be redrawn for
  306. it to take effect.
  307.  
  308. Sliders won't be displayed if a window becomes too small.
  309.  
  310. twsetleftrightevent(winframeptr, callproc event);
  311. twsetupdownevent(winframeptr wf, callproc event);
  312.  
  313. These set the event to be called after a slider has been moved. This
  314. means either the slider thumb or the end point buttons.
  315.  
  316. twsetleftrightrange(winframeptr wf, int range, int step);
  317. twsetupdownrange(winframeptr wf, int range, int step);
  318.  
  319. The slider movement can be gauged by setting its range (from 0 to
  320. range) and the step. Range is an arbitrary value that would reflect the
  321. item that the slider is used to scroll. Step is the increment value to
  322. use with the end point buttons.
  323.  
  324. Menus -
  325.  
  326. Two functions provide for a straight forward local menu facility. On both
  327. the string parameter is the displayed menu selection. Active is to set
  328. whether the menu item is to be active (clickable). If a menu item is
  329. passed with tildes '~' around a character then that item is displayed
  330. with an underscore and the appropriate keypress is trapped (if the
  331. window is active).
  332.  
  333. twmenuitem(winframeptr wf, char *s, unsigned char active);
  334.  
  335. Add a local bar menu item to the window. After adding a bar menu item
  336. the sub menu items must be delared immediately afterward using
  337. twSubMenuItem.
  338.  
  339. twsubmenuitem(winframeptr wf, char *s, unsigned char active, callproc event);
  340.  
  341. Add a submenu item to the local bar menu item most recently added.
  342. Event is the event-handler to call when the sub menu item is selected.
  343.  
  344.  
  345. An important consideration with windows that have local menus is the
  346. imagestkptr that is passed to the event-handler. It is not the imagestkptr of
  347. the Window but of the smaller frame that the menu is displayed in. This
  348. is consistent in that an event-handler is always passed the frame that
  349. the mouse click originated on. To determine what window this event-handler
  350. is being called from use the related stack as in ifs^.related stack.
  351.  
  352. BEGINFILE> twwin4.c
  353.   /* -- twwin4.c */
  354.  
  355. #include "teglsys.h"
  356.  
  357. winframeptr  wf;
  358.  
  359.  
  360.  
  361.   /* -- RedrawIt is a standard event-handler. It is called after  */
  362.   /* -- the window standard items have been drawn.  */
  363.  
  364.  
  365. unsigned redrawit(imagestkptr  ifs, msclickptr   ms)
  366.   { winframeptr  wf;
  367.  
  368.     wf = findwinframe(ifs);
  369.     twputpict(wf,10,10,&imageSYSTEM,BLACK);
  370.     return 0;
  371.   }
  372.  
  373.   /* -- this is the close event for the window.  */
  374.  
  375.  
  376. unsigned closeit(imagestkptr  ifs, msclickptr   ms)
  377.   { winframeptr  wf;
  378.       int      i;
  379.       int      color;
  380.  
  381.     wf = findwinframe(ifs);
  382.     prepareforupdate(ifs);
  383.       /* -- prove that we are going through here  */
  384.     color = 0;
  385.     for (i = 0; i <= 100; i++)
  386.       {
  387.     twsetfillcolor(wf,color);
  388.     twclear(wf);
  389.     color++;
  390.     if (color > 15) color = 0;
  391.       }
  392.     commitupdate();
  393.       /* -- then call close to actually dispose of the window  */
  394.     twclose(wf);
  395.     return 0;
  396.   }
  397.  
  398.   /* -- this event-handler just chains to CloseIt, the important  */
  399.   /* -- notation here is the use of the related stack for local  */
  400.   /* -- menu selections to determine the correct WinFramePtr  */
  401.  
  402.  
  403. unsigned menucloseit(imagestkptr  ifs, msclickptr   ms)
  404.   {
  405.     return closeit(ifs->relatedstack,ms);
  406.   }
  407.  
  408.  
  409.  
  410. void main(void)
  411. {
  412.   tweasystart();
  413.  
  414.   twinit(&wf,100,50,300,190);
  415.     twsetheader(wf,"Window with a local menu");
  416.     twsetmaximize(wf,FALSE);   /* -- no minimize/maximize */
  417.     twsetredraw(wf,redrawit);
  418.     twsetcloseevent(wf,closeit);
  419.     twmenuitem(wf,"~F~ile",TRUE);
  420.     /* -- NilUnitProc is just a dummy event-handler, use it  */
  421.     /* -- as a place holder when you are just building an interface  */
  422.       twsubmenuitem(wf,"~O~pen",TRUE,nilunitproc);
  423.       twsubmenuitem(wf,"-",FALSE,nilunitproc);
  424.       twsubmenuitem(wf,"E~x~it",TRUE,menucloseit);
  425.       twmenuitem(wf,"~D~raw",TRUE);
  426.       twsubmenuitem(wf,"~A~rc",FALSE,nilunitproc);
  427.       twsubmenuitem(wf,"~C~ircle",FALSE,nilunitproc);
  428.       twsubmenuitem(wf,"~E~llipse",FALSE,nilunitproc);
  429.       twsubmenuitem(wf,"~R~ectangle",FALSE,nilunitproc);
  430.   twdrawwindowframe(wf);
  431.  
  432.   teglsupervisor();
  433. }
  434.  
  435.  
  436.  
  437. ENDFILE>
  438.  
  439.  
  440. Any of the example programs that start with a 'TW' are examples of
  441. the high-level window interface.
  442.  
  443. -------------------------------------------------------------------
  444. END TWQUICK.TXT
  445.